Day5: 版本控制：讓 AI 的每次修改都能被看見、被回復

Day4 提到，階段一要處理的問題是：當 AI 對 codebase 做了一次修改，我們如何控制它？在判斷這次修改「對不對」之前，還有兩件更基本的事：知道它改了什麼，以及改壞時能回到哪裡。 這就是版本控制的工作。

What is 版本控制

版本控制是對專案變化的系統性紀錄。它保存專案在各個時間點的狀態，讓我們能比較任兩個版本的差異、查閱修改的歷史，並在需要時回到先前的狀態。

Git 是目前最普遍的版本控制工具。在 Git 中，保存版本的基本單位是 commit：每個 commit 記錄當下的檔案狀態，以及作者、時間與說明。Git 的基本操作都在本機完成，不需要網路或 GitHub 帳號；GitHub 則是託管 Git 儲存庫的平台，多人協作時才會用到，留到明天再談。

Why we need 版本控制

想像一個情境：請 agent 實作一個功能，幾分鐘後它回報完成，總共改了 8 個檔案。執行之後，原本正常的功能壞了。

問題來了：是哪一處修改造成的？改之前的程式長什麼樣子？

人自己修改時，速度慢，範圍也小，多少還記得動過哪裡；agent 則在一次任務中橫跨多個檔案，修改的速度遠超過我們追蹤的速度。若沒有版本控制，能依賴的只剩兩種記憶：我們自己的，以及 agent 的。而 agent 對「原本的程式」的認知，只存在於它當下的 context 裡；Day3 談過，context 可能不完整、也可能已經被後來的修改覆蓋。

因此，版本控制的價值在於：把「改了什麼」與「改之前是什麼」從記憶中移出來，變成可以查閱的紀錄。

Git 在控制迴圈中的三個角色

Commit：建立 checkpoint

commit 之前，Git 會先讓我們選擇這次要保存的內容。修改先加入暫存區（staging area），再由 git commit 保存成一個版本：

git add todo.md
git commit -m "新增文章待辦清單"

暫存區存在的理由，是一次開發往往同時產生多項修改，但它們未必屬於同一個目的。先選擇、再提交，才能讓每個 commit 只包含一件事。

這件事比看起來重要：commit 的粒度，就是之後能回復的粒度。 若一個 commit 同時包含新功能與一段無關的重構，之後想撤銷其中一個，就只能連另一個一起撤銷。

Diff：看見修改

在提交之前，或 agent 回報完成之後，第一步是看它改了什麼：

git status            # 哪些檔案被修改、新增，哪些已暫存
git diff              # 尚未暫存的修改內容
git diff --staged     # 已暫存、將納入下一次提交的內容

檢查 agent 的修改時，diff 是成本最低的第一道 review。在細讀邏輯之前，先確認修改範圍：是否動到了與任務無關的檔案？是否刪掉了不該刪的內容？這些問題不需要理解程式，只要看 diff 就能發現。

也要注意，agent 在回報時給出的修改摘要，是它認為自己做了什麼；diff 則是實際發生了什麼。兩者不一致時，以 diff 為準。

Revert：回到已知的狀態

當修改已經提交，可以用 git log 找到目標，再用 git revert 撤銷：

git log --oneline         # 列出提交紀錄，找到要撤銷的 commit
git revert HEAD --no-edit # 撤銷最近一次提交

git revert 不會刪除歷史，而是新增一個反向套用的 commit。原本的修改與撤銷的紀錄都會保留，事後仍能追查「改過什麼、為什麼又改回來」。

若修改尚未提交，則可以用 git restore <file> 丟棄工作目錄中的修改。但這個操作無法復原，而且只能回到最近一次 commit 的狀態。換句話說，Git 只能保護已經提交的內容；沒有 commit 過的狀態，就沒有可以回去的地方。

完整的操作流程與 VS Code 介面，可以參考 Pro Git：Git 基礎 與 VS Code：Source Control。

如何搭配 coding agent

上面三個角色，對應到與 agent 合作時的三個習慣：

• 開工前留下 checkpoint：交付任務之前，先確認工作目錄乾淨，或把目前的修改提交。agent 改壞時，才有明確的狀態可以回去。
• 小步提交：請 agent 每完成一個可驗證的步驟就提交一次，並在說明中寫下修改目的。這讓回復的粒度變細，也讓 git log 成為這次任務的工作紀錄。
• 用 diff 驗收，用 commit 指定目標：驗收時看 diff，而不只看 agent 的摘要；需要撤銷時，以 commit 識別碼指定目標，而不是說「改回去」。「回去」指的是哪個版本，對人與 agent 都可能不一樣。

實際下指令時，可以這樣描述：

• 「檢查目前尚未提交的修改，依修改目的分組，說明每組改了哪些檔案。先回報，不要提交。」
• 「將新增截止日期的修改建立成一筆提交，其他修改先保留。完成後回報 commit 識別碼與納入的檔案。」
• 「確認工作目錄乾淨後，使用 git revert 撤銷 commit a1b2c3d，完成後回報檔案變化與新增的提交紀錄。」

限制與成本

• Git 不知道對錯：它記錄的是文字的變化，不理解程式的行為。diff 看起來乾淨，不代表修改是正確的；判斷正確性，要交給後面幾天介紹的 linter、type checker 與 test。
• 未提交的修改沒有保護：checkpoint 只存在於 commit 之中。若 agent 在兩次提交之間連續修改，中間的狀態就無法個別回復。
• 紀錄的品質取決於提交的習慣：粒度太粗，回復時會連帶撤銷無關的修改；說明寫得含糊，歷史就難以追查。這些規則需要事先約定，寫進專案的協作規範裡。

Git 讓每次修改都能被看見、被回復，但哪些修改該保存、哪些該撤銷，仍然由我們決定。

到目前為止，都只有一條修改路線。當同事與 agent，或多個 agent 同時修改同一個專案時，又該如何整合？明天來談多人開發。